Manipulating Pen Width and Placement (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Manipulating Pen Width and Placement
The pen width property of a style object determines the width with which QuickDraw GX draws a shape's contours, and three of the style attributes determine where QuickDraw GX places the pen in relation to a shape's contours. These three attributes are

the center-frame style attribute (gxCenterFrameStyle)
the inside-frame style attribute (gxInsideFrameStyle)
the outside-frame style attribute (gxOutsideFrameStyle)

Since contour direction and crossed contours affect pen placement, the examples in this section use a path shape shaped like a figure eight, as defined in Listing 3-7.
Listing 3-7 Defining a figure eight
void CreateFigureEight(void)
{
   gxShape aPathShape;

   static long figureEightGeometry[] = {1, /* number of contours */
                                        4, /* number of points */
                                        0xF0000000, /* 1111 ... */
                                        ff(50), ff(50), 
                                        ff(200),  ff(200), 
                                        ff(50), ff(200),
                                        ff(200),  ff(50)};

   aPathShape = GXNewPaths((gxPaths *) figureEightGeometry);
   GXSetShapeFill(aPathShape, gxClosedFrameFill);

   GXDrawShape(aPathShape);

   GXDisposeShape(aPathShape);
}
Figure 3-47 shows the result of this sample function with the default pen width, which is a hairline, and the default pen placement, which is centered (as it always is for hairlines).
Figure 3-47 A hairline figure eight

To increase the width of the pen, you can add the following line of code to the CreateFigureEight sample function:
GXSetShapePen(aPathShape, ff(30));
which results in the shape depicted in Figure 3-48.
Figure 3-48 A thick figure eight

To change the placement of the thick pen, you can use the GXSetShapeStyleAttributes function to set the inside-frame style attribute or outside-frame style attribute. For example, if you add this line of code to the CreateFigureEight sample function:
GXSetShapeStyleAttributes(aPathShape, gxInsideFrameStyle);
QuickDraw GX shifts the entire pen width, which is 30 points, to the inside of the figure eight. Since, by default, QuickDraw GX defines the inside of a contour to be the right side, contour direction is significant in this case, and the resulting shape appears as depicted in Figure 3-49.
Figure 3-49 A figure eight with pen inset

If you indicate that the pen should be placed outside--that is, to the left of--the contour, using this line of code:
GXSetShapeStyleAttributes(aPathShape, gxOutsideFrameStyle);
the figure reverses, appearing as shown in Figure 3-50.
Figure 3-50 A figure eight with pen outset

The contour direction of the path shape determines which side is the inside and which side is the outside. If you reverse the contour direction by reversing the order of the geometric points with this definition:
static long figureEightGeometry[] = {1, /* number of contours */
                                     4, /* number of points */
                                     0xF0000000, /* 1111 ... */
                                     ff(200), ff(50)
                                     ff(50),  ff(200),
                                     ff(200), ff(200),
                                     ff(50),  ff(50)};
but still set the outside-frame style attribute:
GXSetShapeStyleAttributes(aPathShape, gxOutsideFrameStyle);
then the resulting shape appears to be the same as the original figure-eight shape with the path inset, as shown in Figure 3-51.
Figure 3-51 A reversed figure eight with pen outset

However, this figure still doesn't look like a figure eight with the path outset--it looks like a figure eight with the upper half of the path outset and the lower half of the path inset. This problem arises because the path crosses itself. To fix this problem, you can call the GXSimplifyShape function, which redefines the geometry of the shape so that the path has no crossed contours. Listing 3-8 shows a sample function that uses the GXSimplifyShape to remove the unwanted contour crossing.
Listing 3-8 Removing unwanted contour crossings
void CreateUncrossedFigureEight(void)
{
   gxShape aPathShape;

   static long figureEightGeometry[] = {1, /* number of contours */
                                        4, /* number of points */
                                        0xF0000000, /* 1111 ... */
                                        ff(50),  ff(50), /* off */
                                        ff(200), ff(200),/* off */ 
                                        ff(50),  ff(200),/* off */
                                        ff(200), ff(50)};/* off */
                           
   aPathShape = GXNewPaths((gxPaths *) figureEightGeometry);
   GXSetShapeFill(aPathShape, gxClosedFrameFill);
   GXSetShapePen(aPathShape, ff(30));
   GXSimplifyShape(aPathShape);
   GXSetShapeStyleAttributes(aPathShape, gxAutoInsetStyle);
   GXSetShapeStyleAttributes(aPathShape, gxOutsideFrameStyle);
   
   GXDrawShape(aPathShape);
   
   GXDisposeShape(aPathShape);
}
This sample function calls GXSimplifyShape to uncross the contours of the figure eight. However, you cannot be sure whether GXSimplifyShape uncrosses the contours by reversing the direction of the upper half of the figure eight, making each loop clockwise, or by reversing the lower half of the figure eight, making each loop counterclockwise. Therefore, the CreateUncrossedFigureEight sample function sets the auto-inset style attribute, which overrides the default assumption that the right side of the contour is the inside. Instead, QuickDraw GX determines the true inside of each contour.
Finally, now that the contours of the path do not cross and QuickDraw GX is determinng the actual inside of the contour, setting the outside-frame style attribute works more as you would expect, as shown in Figure 3-52.
Figure 3-52 Uncrossed figure eight with pen outset

For more information about pen placement, see "Pen Placement" beginning on page 3-18. For more information about style attributes, see "Style Attributes" beginning on page 3-17 and "Style Attributes" beginning on page 3-98.